From 5aa3b38185e30fe5793b237fb82036a4317cf8b4 Mon Sep 17 00:00:00 2001 From: Alex Crichton Date: Sun, 7 Sep 2014 17:07:07 -0700 Subject: [PATCH] Clarify why bins have Cargo.lock but libs don't Closes #525 --- src/doc/source/faq.md | 27 ++++++++++++++++++++++++++- 1 file changed, 26 insertions(+), 1 deletion(-) diff --git a/src/doc/source/faq.md b/src/doc/source/faq.md index 011f3e01a..e571f5b17 100644 --- a/src/doc/source/faq.md +++ b/src/doc/source/faq.md @@ -113,4 +113,29 @@ issue][3]. [3]: https://github.com/rust-lang/cargo/issues - +# Why do binaries have `Cargo.lock` in version control, but not libraries? + +The purpose of a `Cargo.lock` is to describe the state of the world at the time +of a successful build. It is then used to provide deterministic builds across +whatever machine is building the project by ensuring that the exact same +dependencies are being compiled. + +This property is most desirable from applications and projects which are at the +very end of the dependency chain (binaries). As a result, it is recommended that +all binaries check in their `Cargo.lock`. + +For libraries the situation is somewhat different. A library is not only used by +the library developers, but also any downstream consumers of the library. Users +dependent on the library will not inspect the library's `Cargo.lock` (even if it +exists). This is precisely because a library should **not** be deterministically +recompiled for all users of the library. + +If a library ends up being used transitively by several dependencies, it's +likely that just a single copy of the library is desired (based on semver +compatibility). If all libraries were to check in their `Cargo.lock`, then +multiple copies of the library would be used, and perhaps evan a version +conflict. + +In other words, libraries specify semver requirements for their dependencies but +cannot see the full picture. Only ends products like binaries have a full +picture to decide what versions of dependencies should be used. -- 2.30.2